package suncertify.db;

/**
 * The public interface that all objects must implement that 
 * want to perform I/O functionality for the application's database file.
 * The <code>DBMain</code> class allow classes to run queries on, and search
 * the database file.
 * @author Sun Corporation
 *
 */
public interface DBMain {
	/**
	 * Reads a record from the file.
	 * @param recNo - The record number to read
	 * @return A String[] where each element is the record value.
	 * @throws RecordNotFoundException
	 */
	public String [] read(int recNo) throws RecordNotFoundException;
	
	/**
	 * Modifies the fields of a record. The new value for field n 
	 * appears in data[n].
	 * @param recNo - The record number to update
	 * @param data - The data with which to update the record
	 * @throws RecordNotFoundException
	 */
	public void update(int recNo, String [] data)
	throws RecordNotFoundException;

	/**
	 * Deletes a record, making the record number and associated disk
	 * storage available for reuse. 
	 * @param recNo - The record to delete
	 * @throws RecordNotFoundException
	 */
	public void delete(int recNo) throws RecordNotFoundException;
	
	/**
	 * Finds a record in the database. A null value in criteria[n] matches any field
	 * value. A non-null  value in criteria[n] matches any field
	 * value that begins with criteria[n]. (For example, "Fred"
	 * matches "Fred" or "Freddy").
	 * @param criteria - A String[] describing the criteria.  Field n in the database
	 * is described by criteria[n].
	 * @return An array of record numbers that match the specified criteria.
	 * @throws RecordNotFoundException
	 */
	public int [] find(String [] criteria)
	throws RecordNotFoundException;
	
	/**
	 * Creates a new record in the database (possibly reusing a
	 * deleted entry).
	 * @param data - The data for the new record
	 * @return The record number of the new record.
	 * @throws DuplicateKeyException
	 */
	public int create(String [] data) throws DuplicateKeyException;
	
	/**
	 * Locks a record so that it can only be updated or deleted by this client.
	 * If the specified record is already locked, the current thread gives up
	 * the CPU and consumes no CPU cycles until the record is unlocked.
	 * @param recNo - The record number to lock
	 * @throws RecordNotFoundException
	 */
	public void lock(int recNo) throws RecordNotFoundException;
	
	/**
	 * Releases the lock on a record.
	 * @param recNo - The record number to release
	 * @throws RecordNotFoundException
	 */
	public void unlock(int recNo) throws RecordNotFoundException;
	
	/**
	 * Determines if a record is currently locked. Returns true if the
	 * record is locked, false otherwise.
	 * @param recNo - The record number to check
	 * @return Whether the record is locked or not
	 * @throws RecordNotFoundException
	 */
	public boolean isLocked(int recNo)
	throws RecordNotFoundException;
}

